---
title: Development Setup
description: Set up a local Latitude instance using Docker for development and testing.
---

# Development Setup

This guide explains how to set up a local instance of Latitude on your machine for development, testing, or contributing to the project. We primarily use Docker Compose to manage the necessary services.

<Note>
  Due to potential performance limitations with Next.js in Docker volume mounts
  on some systems, parts of the development setup might involve running services
  directly on the host. This guide focuses on the Docker Compose approach.
</Note>

## Prerequisites

- **Git**: To clone the repository.
- **Docker & Docker Compose**: Ensure Docker Desktop or equivalent is installed and running.
- **Node.js & pnpm**: Required for building packages and potentially running some services locally. Install [pnpm](https://pnpm.io/installation).
- **Tmux & Tmuxinator (Optional but Recommended)**: Useful for managing multiple services in the terminal. Install [Tmuxinator](https://github.com/tmuxinator/tmuxinator) (e.g., `brew install tmuxinator` on macOS).

## Setup Steps

1.  **Clone the Repository**:

    ```bash
    git clone https://github.com/latitude-dev/latitude-llm.git
    cd latitude-llm
    ```

2.  **Install Dependencies**:

    ```bash
    pnpm install
    ```

3.  **Build Shared Packages**:
    Build the core packages that other services depend on.

    ```bash
    pnpm build --filter='./packages/**'
    ```

4.  **Configure Environment (if needed)**:

    - Copy any example environment files (e.g., `.env.example` to `.env`) and adjust necessary variables. For a standard local setup, defaults are often sufficient.

5.  **Start Services with Docker Compose**:
    This command starts the database, message queue, and other background services defined in `docker-compose.yml`.

```bash
docker compose up -d
```

<Info>
  The Docker Compose setup pulls pre-built images from GitHub Container Registry (ghcr.io/latitude-dev).
  To build local images after making code changes, add the `--build` flag (e.g., `docker compose up -d --build`).
</Info>

    _Alternatively, if using Tmuxinator (recommended)_:

    ```bash
    tmuxinator start
    ```

    This will typically start Docker Compose in one pane and potentially other services (like the web app) in other panes according to the `.tmuxinator.yml` config.

6.  **Run Database Migrations**:
    Once the database container is running (check `docker compose ps` or the tmuxinator output), apply the necessary database schema migrations.

    ```bash
    cd packages/core
    pnpm db:migrate
    cd ../..
    ```

7.  **Run the Web Application (if not using Tmuxinator)**:
    If you didn't use tmuxinator, you might need to start the Next.js web application manually:
    ```bash
    pnpm dev --filter web
    ```

## Accessing Local Latitude

- **Web UI**: Open your browser to `http://localhost:3000` (or the configured port).
- **Sign Up**: Create your first user account using any email address.
- **Email Confirmation**: Access the local MailHog instance (usually at `http://localhost:8025`) to find the confirmation email and complete the signup.
- **API**: The local API will be available (check `docker-compose.yml` or app configuration for the port, often proxied through the web UI).

## Configuration

- **Docker Compose**: Modify `docker-compose.yml` to adjust service configurations, ports, or volumes.
- **Environment Variables**: Core settings (database URLs, API keys for testing, etc.) are typically managed via `.env` files within the respective app/package directories.
- **Application Config**: Check specific application directories (e.g., `apps/web/config`) for further configuration options.

## Stopping the Environment

- **Docker Compose**: `docker compose down`
- **Tmuxinator**: Stop the session (e.g., `tmux kill-session -t latitude-llm`) or stop individual services in their panes.

Now you have a local Latitude instance running for development!

## Using the REPL

You can run a JavaScript REPL to interact with the local instance of Latitude.
From the root of the repository, start the REPL with `pnpm console`. Try:

```javascript
await database.select().from(users).limit(10)
```

## Next Steps

- Learn about deploying to [Production](/guides/self-hosted/production-setup)
- Explore the [Project Structure](/meta/project-structure)
